CONTROL ADD LISTVIEW statement

Purpose

Add a ListView control to a dialog. A ListView displays a set of predefined string data items in one or more columns. The user may then view the items, selecting one or more of them for use in the program at a later time.

Syntax

CONTROL ADD LISTVIEW, hDlg, id&, txt$, x, y, xx, yy [, [style&] [, [exstyle&]]] [[,] CALL callback]

hDlg

Handle of the dialog in which the ListView will be created. The dialog will become the parent of the control.

id&

Unique identifier for the control in the range 1 to 65535, frequently specified with numeric equates for clarity of the code. For example, the equate %PickList is more informative than a literal value such as 497. Best practice suggests identifiers should start at 100 to avoid conflict with any of the standard predefined identifiers.

txt$

Text to associate with the ListView control. A ListView control does not display this text, so it is common to set this value to a null, empty string literal ("").

x,y

Integer expressions, variables, or numeric literal values specifying the location of the control inside the dialog client area. x is the horizontal position, and y is the vertical position. 0,0 refers to the upper left corner of the dialog box client area. Coordinates are specified in the same terms (pixels or dialog units) as the parent dialog.

xx,yy

Integral expressions, variable, or numeric literal values, specifying the width and height of the control. xx is the width and yy is the height, given in the same terms (pixels or dialog units) as the parent dialog.

style&

Primary style of the ListView control. The default ListView style comprises %WS_TABSTOP, %LVS_REPORT, and %LVS_SHOWSELALWAYS. This default ListView style is used if the style parameters are omitted from the statement, as in the following example:

CONTROL ADD LISTVIEW, hDlg, id&, "", 100, 100, 150, 200, , , CALL LVCallback()

If you include explicit style values, they replace the default values. That is, they are not added to the default styles values - your code must specify all necessary primary and extended style parameters.

The primary ListView style value can be a combination of any values below, combined together with the OR operator to form a bitmask:

%LVS_ALIGNLEFT	Items are left-aligned in icon and small icon view.
%LVS_ALIGNTOP	Items are aligned with the top of the control in icon and small icon view.
%LVS_AUTOARRANGE	Icons are automatically kept arranged.
%LVS_EDITLABELS	Item text can be edited by the user. The parent window must process notification messages.
%LVS_ICON	This style specifies icon view.
%LVS_LIST	This style specifies list view.
%LVS_NOCOLUMNHEADER	In report view, there are no headers on the columns.
%LVS_NOLABELWRAP	Item text is displayed on a single line in icon view.
%LVS_NOSCROLL	No scroll bars are provided. Incompatible with list view and report view.
%LVS_NOSORTHEADER	Report view column headers are flat, not like buttons. User can not click on the header to generate a column click notification.
%LVS_OWNERDATA	This style specifies a virtual ListView control.
%LVS_OWNERDRAWFIXED	The owner window can paint items in report view.
%LVS_REPORT	This style specifies report view. The first column is always left-aligned and columns have headers.
%LVS_SHAREIMAGELISTS	The image list will not be deleted when the control is destroyed.
%LVS_SHOWSELALWAYS	Selections are always shown, even without the focus.
%LVS_SINGLESEL	Only one item at a time can be selected. By default, multiple items may be selected.
%LVS_SMALLICON	This style specifies small icon view.
%LVS_SORTASCENDING	Item indexes are sorted as added in ascending order.
%LVS_SORTDESCENDING	Item indexes are sorted as added in descending order.
%WS_DISABLED	Create a control that is initially disabled. A disabled control cannot receive input from the user.
%WS_GROUP	Define the start of a group of controls. The first control in each group should also use %WS_TABSTOP style. The next %WS_GROUP control in the tab order defines the end of this group and the start of a new group.
%WS_TABSTOP	Allow the control to receive keyboard focus when the user presses the TAB and SHIFT+TAB keys. The TAB key shifts keyboard focus to the next control with the %WS_TABSTOP style, and SHIFT+TAB shifts focus to the previous control with %WS_TABSTOP.

exstyle&

Extended style of the ListView control. The default extended style is %WS_EX_LEFT. The default extended style is used if both the primary and extended parameters are omitted from the CONTROL ADD LISTVIEW statement, in the same manner as style& above.

The extended ListView style value can be a combination of any values below, combined together with the OR operator to form a bitmask:

%WS_EX_CLIENTEDGE	Apply a sunken edge border to the control.
%WS_EX_LEFT	The control has generic "left-aligned" properties. (default)
%WS_EX_RIGHT	The control has generic "right-aligned" properties. This style has an effect only if the shell language is Hebrew, Arabic, or another language that supports reading order alignment; otherwise, the style is ignored.
%WS_EX_STATICEDGE	Apply a three-dimensional border style to the control (intended to be used for items that do not accept user input).
%WS_EX_TRANSPARENT	Controls/windows beneath the control are drawn before the control is drawn. The control is deemed transparent because elements behind the control have already been painted - the control itself is not drawn differently. True transparency is achieved by using Regions - see MSDN for more information.
%WS_EX_WINDOWEDGE	Apply a raised edge border to the control.

callback

Optional name of a Callback Function that receives all %WM_COMMAND and %WM_NOTIFY messages for the control. See the #MESSAGES metastatement to choose which messages will be received. If a callback for the control is not designated, you must create a dialog Callback Function to process messages from your control.

If the Callback Function processes a message, it should return TRUE (non-zero) to prevent the message being passed unnecessarily to the dialog callback (if one exists). The dialog callback should also return TRUE if the notification message is processed by that Callback Function. Otherwise, the DDT engine processes unhandled messages.

Remarks

When a Callback Function receives a %WM_COMMAND message, it should explicitly test the value of CB.CTL and CB.CTLMSG to guarantee it is responding appropriately to the notification messages.